<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
		<title>jsTree.generator :: Generator Rules</title>
		<link rel="stylesheet" href="3gen.docs.css" type="text/css" />		
	</head>
	<body>
		<h1>M3Gen :: RuleSet configuration</h1>
		<p>
		The RuleSet configuration is an object containing rules and ruleSets that define how to parse a json structure, how to handle different types of objects encountered 
		and how to generate each jsTree node and hence the entire jsTree model.
		A RuleSet configuration object has the following keys:<br/>
		Required:
		<ul>
			<li>selectObjType : string (fx "person") - <span class="desc">The function used to decide which ruleSet to use for handling the specific object encountered</span></li>
			<li>ruleSets: ruleSet container (see below) - <span class="desc">Defines ruleSets matching each supported objType (as returned by selectNodeType) in the instanceModel parsed</span></li>
		</ul>
		Optional:
		<ul>
			<li>pathMethod : string ("xpath" | "jpath") - <span class="desc">Which path function to use (see pathFunctions)</span></li>
			<li>branchTypes : branch array (see below) - <span class="desc">Defines how to create branches of various types</span></li>
			<li>iconsPath : string (fx "../images/icons") - <span class="desc">Defines the base path for icons</span></li>
			<li>ruleSetsEnabled : string array (fx ["person"]) - <span class="desc">A list of ruleSets that are explicitly enabled (empty list indicates all ruleSets are enabled)</span></li>
			<li>ruleSetsDisabled : string array (fx ["person"]) - <span class="desc">A list of ruleSets that are explicitly disabled</span></li>
			<li>useUniqueId : boolean (true | false) - <span class="desc">Whether to use the unique ID created as the id for the jsTree node </span></li>
			<li>defaultState : string ("open" | "closed") - <span class="desc">Default state (open|closed) of any jsTree node created </span></li>
		</ul>				
		</p>
		<h2>branchTypes</h2>
		<p>
			branchTypes is an object with keys for each defined type of branch folder.
			Each key has a value, in the form of an object with an 'icon' and 'state' value.
			Icon defines the icon used relative to the iconsPath (is appended to iconsPath). 
			State defines if the branch folder will by default be shown as "open" or "closed".
			If a branchType is not found, by default {icon: 'folder.png', state: 'closed'} will be used.
			<div class="example">Example of a branchTypes</div>
			<code>
				{
					folder: 		{icon: 'folder.png', state: 'closed'}, 
					personFolder: 	{icon: 'person/folder.png', state: 'open'}
				}
			</code>
		</p>
		<h2>ruleSets</h2>
		<p>
			The ruleSets key contains an object with a key for each ruleSet.
			selectNodeType returns a string which is used to lookup a ruleSet within ruleSets that has a key with the same name.
			If selectNodeType returns "person", ruleSchemas must have a key "person" that is assigned a ruleSet which 
			specifies how to handle a "person" object.
			<code>
				{
					person:  { ... },
					company: { ... }
				}
			</code>	
			<ul>
				<li>functions : function object - <span class="desc">Contains functions for handling specific aspects of the generating process, specific for this nodeType</span></li>
				<li>childBranches : array of branchRule - <span class="desc">Defines how to create jsTree nodes for object children</span></li>
				<li>refBranches  : array of branchRule - <span class="desc">Defines how to create jsTree nodes for object references (or children to be treated as references)</span></li>
			</ul>
			The following keys can be set to override the global (default) ruleSetConfiguration settings
			<ul>
				<li>iconsPath  : string (fx "../images/icons") - <span class="desc">Overrides global iconsPath for this nodeType</span></li>
				<li>defaultState : string ("open" | "closed") - <span class="desc">Overrides global defaultState for this nodeType</span></li>
				<li>useUniqueId  : boolean (true | false) - <span class="desc">Overrides global useUniqueId for this nodeType</span></li>
				<li>branchTypes : branch array - <span class="desc">Overrides global branchTypes for this nodeType</span></li>				
			</ul> 			
			<h3>Branch Rules</h3>
			<p>
				A branchRule contains the following keys:
				<ul>
					<li>branchNode</li>
					<li>selectors</li>
				</ul>
				<h4>branchNode</h4>
				<p>
					<ul>
						<li>id - The 'id' of the jsTree node to be created</li>
						<li>title - The 'title' of the jsTree node to be created</li>
						<li>branchType - The branchType key to look up in branchTypes</li>
					</ul>
				</p>
				<h4>selectors</h4>
				<p>
					An array of selectors. Each array entry can either be a string with a path, defining where to find one or more objects or
					a function that returns an array of objects given an object. The function approach is more flexible and allows "business rules" to be
					incorporated into the selection process, but the path approach is simpler, clearer and usable in most cases.
				</p>
				<h4>Example of Branch Rules</h4>
				<code>
				  [
				  	{
						branchNode: {
							id: 'boys', 
							title:'My boys', 
							branchType: 'folder'
						}, 
						selectors: ['myChildren.boys', personSelectFunctions.boy18Selector]
					}, 
				  	{
						branchNode: {
							id: 'girls', 
							title:' My girls', 
							state: 'open', 
							branchType: 'folder'
						}, 
						selectors: ['myChildren.girls', personSelectFunctions.selectFriends]
						}
				  ]					
				</code>				
			</p>
			<h3>Examples of RuleSets</h3>
			<p>
				<div class="example">Example of a ruleSet for nodeType "person"</div>		
				<code>
				  	'person': { 
						 	  branchTypes: {'folder': {icon: 'folder.png', state: 'closed'}},
							  functions: personSelectFunctions,
							  defaultState: 'closed', 
							  useUniqueId: true,
							  childBranches:[{branchNode: {id: 'boys', title:'My boys', branchType: 'folder'}, selectors: ['myChildren.boys', personSelectFunctions.boy18Selector]}, 
							  			  {branchNode: {id: 'girls', title:' My girls', state: 'open', branchType: 'folder'}, selectors: ['myChildren.girls', personSelectFunctions.selectFriends]}
							  ],
							  refBranches:[{
							  		branchNode: {title:'My siblings', state: 'closed', branchType: 'folder'}, 
							  		selectors: ['siblings']
							  }],
							  iconsPath : 'images/person'
					} 			  
				</code>	

			</p>
			<p>
				<div class="example">Example of a ruleSet for objType "company"</div>			
				<code>
				  	'company': { 
							  functions: companySelectFunctions,
							  defaultState: 'closed',useUniqueId: true,
				              childBranches:[{
							  				branch: {title:'people', state: 'closed', branchType: 'folder'}, 
							  				selectors: ['employees', 'partners']
							  }]
							  ,iconsPath : 'images/company'
					}				
				</code>	
			</p>	
		</p>		
	</body>
</html>
